home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / bpreal.exe / BPREAL.DOC < prev    next >
Text File  |  1993-04-19  |  12KB  |  254 lines
  1.                              BPREAL
  2.               Borland Pascal Real-Type Conversions
  3.                         by Richard Biffl
  4.  
  5.  
  6.      The accompanying module, BPREAL.C, contains functions in the
  7. C language to convert floating-point numbers between the IEEE
  8. "double" type used by most PC-based C compilers and the
  9. proprietary "real" type used by Borland Pascal.  The functions
  10. allow C programs to read numeric data stored by Borland Pascal
  11. programs, and to write numeric data in a format accessible to
  12. Borland Pascal programs.
  13.  
  14.      Recent versions of Borland Pascal, beginning with Turbo
  15. Pascal 4.0, support the same IEEE-standard floating-point types
  16. used by C (and other) compilers, but the use of IEEE types in
  17. Borland Pascal is optional.  Many Pascal programmers continue to
  18. use Borland's default real type because programs that use it do
  19. not require a numeric coprocessor or coprocessor-emulation code.
  20.  
  21.      Borland Pascal can automatically convert values between real
  22. and IEEE formats, but other languages do not have built-in
  23. support for the real type.  The appropriate IEEE type for real
  24. conversions is the 8-byte double-precision type, called double in
  25. both C and Borland Pascal, which can store any value that can be
  26. stored by a 6-byte real.  The real_to_double function in the
  27. BPREAL module performs this conversion, returning a C double.
  28.  
  29.      BPREAL's double_to_real function performs the opposite
  30. conversion, from C double to Borland Pascal real.  The function
  31. can return an error code to indicate whether the original double
  32. value was accurately converted to the narrower real type.
  33.  
  34.  
  35. The Real and Double Formats
  36.  
  37.      The real and double formats comprise three fields:  a sign
  38. bit, a significand field, and an exponent field.  For the real
  39. type, the fields can be visualized as arranged like this, with
  40. the most significant bit at the left end of each field:
  41.  
  42.             Field:  Sign      Significand    Exponent
  43.      Width (bits):    1            39            8
  44.  
  45. The fields of the IEEE double type are arranged like this:
  46.  
  47.             Field:  Sign      Exponent       Significand
  48.      Width (bits):    1          11               52
  49.  
  50. In a PC's memory, these values are stored with the right-most 8-
  51. bit bytes at the lowest address (or first on a disk), so that the
  52. real's exponent would be stored as the first byte and its sign
  53. bit would be the most significant (leftmost) bit of the sixth
  54. byte.
  55.  
  56.      The sign bit is set when the value is less than 0.0
  57. (negative).  The exponent field (8 bits for real, 11 bits for
  58. double) represents the integer part of the base-2 logarithm of
  59. the value, indicating the value's absolute magnitude.  The
  60. exponent is biased by some value (129 for real, 1023 for double),
  61. so although the binary value of the field is positive, it can
  62. signify a negative value when the bias is subtracted from it. 
  63. The significand field (39 bits for real, 52 bits for double) is
  64. the fractional part by which the value indicated by the exponent
  65. is increased.  Thus, for both types, the represented value is
  66. generally
  67.  
  68.  
  69.     Sign           Significand              (Exponent - Bias)
  70. (-1)      *  (1 + -------------------)  *  2
  71.                     SignificandWidth
  72.                    2
  73.  
  74.  
  75.      There are a few special cases.  The value of a real is 0.0
  76. when the exponent field is 0, i.e., when no bit in the exponent
  77. field is set.  The IEEE double has a value of 0.0 when both the
  78. exponent field and the significand field have values of 0, but
  79. the double's sign bit can be set to represent -0.0 as well as
  80. 0.0.  When all 11 bits are set in the double's exponent field, so
  81. that it has its highest possible value (2047), and none of the
  82. bits in the significand field is set, so that its value is 0, the
  83. double's value is Inf (infinity) or -Inf, depending on the sign
  84. bit.  If the double's exponent field is 2047 and its significand
  85. is not equal to 0, the value is NaN (not a number).
  86.  
  87.      The real's format permits an absolute range of approximately
  88. 2.9e-39 to 1.7e38 (decimal) and a precision of 11-12 significant
  89. decimal digits.  The double's wider format offers an absolute
  90. range of approximately 5.0e-324 to 1.7e308 and a precision of 15-
  91. 16 significant digits.  (The tiniest values represented by
  92. doubles sacrifice precision for their very low magnitude.)
  93.  
  94.  
  95. Conversion Functions
  96.  
  97.      Conversion between a real and a double mainly involves
  98. transferring the bit fields from the source to the target. 
  99. Because there is no high-level access to the bits in a double,
  100. and C has no real type, both double and real must be treated as
  101. arrays, the elements of which can be manipulated individually at
  102. the bit level.  Instead of treating doubles and reals as arrays
  103. of bytes, it is more efficient to treat them as arrays of 16-bit
  104. unsigned ints.  A typedef statement in BPREAL.C declares the
  105. "real" type as an array of 3 unsigned ints, and a "doublearray"
  106. union so that doubles can be handled as arrays of 4 unsigned
  107. ints.
  108.  
  109.      The bits contained in each of the arrays' elements are
  110. listed below.  For each element, its contents are listed from
  111. left to right (most significant bit to least significant), and
  112. bit 1 of each field is the field's most significant bit:
  113.  
  114.           real[2]        Sign 1, Significand 1-15
  115.           real[1]        Significand 16-31
  116.           real[0]        Significand 32-39, Exponent 1-8
  117.  
  118.      doublearray.a[3]    Sign 1, Exponent 1-11, Significand 1-4
  119.      doublearray.a[2]    Significand 5-20
  120.      doublearray.a[1]    Significand 21-36
  121.      doublearray.a[0]    Significand 37-52
  122.  
  123.      Conversion from real to double is straightforward, because
  124. any value that can be represented by a real can be represented by
  125. a double.  The real_to_double function first checks whether the
  126. exponent is 0.  If so, it returns the double 0.0.  Otherwise, it
  127. adds 894 to the exponent because the double's exponent bias
  128. (1023) is 894 greater than the real's bias (129), and it places
  129. the exponent in the correct location in the double (element 3,
  130. shifted 4 bits to the left).  It then moves the sign bit and the
  131. 39-bit significand to their proper locations.
  132.  
  133.      Conversion from double to real is trickier, because the IEEE
  134. type has greater range and precision and more special cases than
  135. the real.  Since error-free conversion is not assured, the
  136. double_to_real function returns an error code of an enumerated
  137. type called prconverr (for Pascal Real Conversion Error).  The
  138. error codes range in increasing seriousness from prOK, which
  139. means no error, to prNaN, which means that the double value was
  140. NaN (not a number), which cannot be represented by a real.
  141.  
  142.      The double_to_real function first checks whether the double
  143. value is 0.0 or -0.0, either of which is converted to a real
  144. representation of 0.0 before returning prOK.
  145.  
  146.      Next, the function checks whether all the bits in the
  147. double's exponent are set.  If they are, the double's value is
  148. either Inf or NaN (or one of their negations).  If the value is
  149. Inf, the real's exponent and significand fields are filled so as
  150. to represent the largest value possible, the sign bit is
  151. transferred, and the code prInf is returned.  If the value is
  152. NaN, a real value of 0.0 and a code of prNaN are returned.
  153.  
  154.      After these tests, the significand is rounded.  The real's
  155. 39-bit significand does not allow as much precision as the
  156. double's 52-bit significand.  To keep as much precision as
  157. possible, the 40th bit of the double's significand is tested.  If
  158. the 40th bit is set, the significand's 39th bit is incremented. 
  159. If all of the first 40 bits of the double's significand are set,
  160. bits 1 to 39 are cleared and the exponent is incremented.  The
  161. exponent field is guaranteed not to be filled, so incrementing
  162. the exponent will succeed, because the function has already
  163. tested the exponent for its maximum value in checking whether the
  164. double's value was Inf or NaN.
  165.  
  166.      After rounding, the function places the value of the
  167. double's exponent in a variable and checks whether it fits within
  168. the range of valid real exponents.  Real e